{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Setup\n",
    "\n",
    "In this series of workshops we will be using [Jupyter Notebook](http://jupyter.org/) as our Integrated Development Environment (<acronym title=\"Integrated Development Environment\" style=\"border-bottom: 1px dashed #999; cursor: help\">IDE</acronym>), and the [Anaconda](https://www.continuum.io/) distribution of Python.\n",
    "\n",
    "## Anaconda\n",
    "\n",
    "Anaconda is a software application that packages together different Python versions and a package manager. There are other options out there, like using your distribution's Python version, or [`pyenv`](https://github.com/pyenv/pyenv), but we won't be covering the setup for those. Therefore, the first thing to do is to download and install the [Anaconda Navigator](https://www.continuum.io/downloads) graphical installer for Python 3.5 (or higher).\n",
    "\n",
    "\n",
    "## Jupyter Notebooks\n",
    "> The Jupyter Notebook App is a server-client application that allows editing and running “notebook“ documents via a web browser [...] In addition to displaying/editing/running notebook documents, the Jupyter Notebook App has a “Dashboard” (Notebook Dashboard), a “control panel” showing local files and allowing to open notebook documents or shutting down their kernels.\n",
    ">\n",
    "> &mdash; <cite>[Jupyter/IPython Notebook Quick Start Guide](http://jupyter-notebook-beginner-guide.readthedocs.io/en/latest/what_is_jupyter.html)</cite>\n",
    "\n",
    "In Jupyter, a kernel is the engine in which commands are run. In our case, the engine will be in Python, specifically, the IPython kernel.\n",
    "\n",
    "Jupyter let's you write and evaluate code at a granular level without re-running scripts constantly and using a lot of print debugging. It also allows mixing in Markdown and HTML within your notebook, and so is a great way of presenting code and data analysis.\n",
    "\n",
    "For getting started, you should go to the official [Jupyter documentation](http://test-jupyter.readthedocs.io/en/latest/index.html), the [starter guide](https://jupyter-notebook-beginner-guide.readthedocs.io/en/latest/), or take a look on [how to run code](https://github.com/jupyter/notebook/blob/master/docs/source/examples/Notebook/Running%20Code.ipynb), or [other interesting notebooks](https://github.com/jupyter/jupyter/wiki/A-gallery-of-interesting-Jupyter-Notebooks). There is even [video tutorials available](https://www.youtube.com/watch?v=HW29067qVWk).\n",
    "\n",
    "## Virtualenvs\n",
    "\n",
    "In the Python world, a `virtualenv`, virtual environment, or just environment, is a way of managing isolated environments so each project can have its own dependencies without conflicts with other projects.\n",
    "\n",
    "> A Virtual Environment is a tool to keep the dependencies required by different projects in separate places, by creating virtual Python environments for them. It solves the “Project X depends on version 1.x but, Project Y needs 4.x” dilemma, and keeps your global site-packages directory clean and manageable.\n",
    ">\n",
    "> &mdash; <cite>[The Hitchhiker’s Guide to Python!](http://python-guide-pt-br.readthedocs.io/en/latest/dev/virtualenvs/)</cite>\n",
    "\n",
    "Anaconda has its own environment and package manager (`conda`), let's you easily set Python versions, and comes with many of the standard packages used in scientific computing. It also provides the concept of channels so you can easily install packages that are maintained by other people. We will be covering the instructions for setting up your Python environment using Anaconda.\n",
    "\n",
    "\n",
    "## Setting up Jupyter using Anaconda in the command line\n",
    "\n",
    "To set up an environment, in your shell or terminal, run (`$` means a shell command):\n",
    "\n",
    "`\n",
    "$ conda create -n name_of_your_environment python=x.y package1 package2\n",
    "`\n",
    "\n",
    "This creates an environment named `name_of_your_environment`, where the Python version is specified to `x.y`, and installs the packages `lib1` and `lib2` into the environment.\n",
    "\n",
    "For example;\n",
    "\n",
    "`\n",
    "$ conda create -n data python=3.5 jupyter requests\n",
    "`\n",
    "\n",
    "Installs `jupyter` and `requests` in a `data` virtualenv using Python 3.5.\n",
    "\n",
    "After you create the environment, run\n",
    "\n",
    "`\n",
    "$ source activate name_of_your_environment\n",
    "`\n",
    "\n",
    "Or\n",
    "\n",
    "`\n",
    "$ activate name_of_your_environment\n",
    "`\n",
    "\n",
    "Depending on whether you are on OSX or Windows to activate the environment.\n",
    "\n",
    "Once you have a virtual environment running, just install `jupyter` and run `jupyter notebook` from the location where you want to store your notebook.\n",
    "\n",
    "`\n",
    "$ jupyter notebook\n",
    "`\n",
    "\n",
    "And go to http://localhost:8888/ in your browser.\n",
    "\n",
    "If you need to install packages from other channels, just add `-c channel_name` to the `install`:\n",
    "\n",
    "`\n",
    "$ conda install -n name_of_your_environment -c channel_name package_maintained_by_someone_else\n",
    "`\n",
    "\n",
    "Often times, we will be using the channel `conda-forge` for more up-to-date or missing packages from the official Anaconda repository.\n",
    "\n",
    "## Setting up Jupyter using Anaconda Navigator\n",
    "\n",
    "First, launch the Anaconda-Navigator interface, go to \"Environments,\" and create a new one with Python 3.5 (or higher) and click on it.\n",
    "\n",
    "![Environment creation](images/anaconda-envs.gif \"Environment creation\")\n",
    "\n",
    "Go to channels and add a new one called `conda-forge`, then click on \"Update channels.\"\n",
    "\n",
    "![Channels](images/anaconda-channels.gif \"Channels\")\n",
    "\n",
    "Now go to the \"Installed\" packages and select \"Not installed.\" Look for \"jupyter\" in the \"Search Packages\" box and mark it to install. Repeat the process for any other package you need, such as \"requests\" for example. Then click on \"Applyl,\" and you should see a list of packages before installing the them. Click \"OK.\"\n",
    "\n",
    "![Packages](images/anaconda-packages.gif \"Packages\")\n",
    "\n",
    "Once installation is finished, click on the green triangle and select \"Open with Jupyter Notebook.\" A terminal window should popup. It's loading Jupyter. After a few seconds you should see the main interface of Jupyter showing the current directory contents.\n",
    "\n",
    "![Launching Jupyter](images/anaconda-jupyter.gif \"Launching Jupyter\")\n",
    "\n",
    "Navigate to where you want your notebooks stored, and then click on \"New\" and select \"Python 3.5\". Now you should be ready to start writing Python code in a new and clean notebook.\n",
    "\n",
    "![Launching a Notebook](images/anaconda-notebook.gif \"Launching a Notebook\")\n",
    "\n",
    "\n",
    "## Final remarks\n",
    "\n",
    "Now you should have all you need to start coding in Python with Anaconda and Jupyter Notebook. We still recommend you to have your code control versioned, preferably with a tool like `git`, to ease history revision and to avoid accidental code loss.\n",
    "\n",
    "Happy coding!"
   ]
  }
 ],
 "metadata": {
  "anaconda-cloud": {},
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.5.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}
